Axiell Portfolio image plugin

The plugin is a .dll file that comes with the Axiell WebAPI, which allows wwwopac.ashx to ingest and retrieve content (e.g. image files) into and from the Extensis Porfolio Server DAMS (Digital Asset Management System) through the Portfolio API.

While an Axiell Collections application like XPlus is primarily intended to catalogue the objects in your collection (along with a Multimedia documentation data source to register the images of those objects separately as well), it is not as effective in organizing, searching and presenting your images and other media files as a good DAMS is. In a media file rich environment, the two systems may therefore complement each other well, but only if a link between the two systems can be established, in the sense that:

all existing images registered in the DAMS should be searchable and retrievable from within Collections;
any new image file to be linked to an object record in Collections should automatically be ingested into the DAMS;
when linking to any new or existing image registered in the DAMS, the catalogue id and asset/item id must be returned to Collections and written to the relevant Collections record to construct the actual link.

From the viewpoint of Extensis, Axiell Collections is third-party software, and to allow third-party software access to the Portfolio Server functionality to search, retrieve, ingest and delete images, the server provides a Portfolio API. In turn, the primary Collections software to communicate with the Portfolio API is the Axiell WebAPI using the plugin. The Axiell WebAPI, being an API, can in principle be addressed by multiple sources as well, like the Axiell Internet Server web application or by custom third-party software. Although deletion of DAMS content is currently limited to direct Axiell WebAPI handling, which is not available through Collections applications, accessing the Portfolio Server functionality by means of Axiell Collections is the main focus of the Axiell/Portfolio connection..

File update functionality is currently not part of this implementation. When linking an image in Collections, only the image file and its name will be submitted to Portfolio, no other (meta)data will be ingested, and changing an image once it’s been linked to a Collections record will probably be a rare occasion. The integration also offers no synchronization capabilities beyond the initial one when the media file is actually being linked by means of the asset id, but then: the Axiell Portfolio plugin is designed to offer both systems ingest and read access to the same pool of digital assets, it’s not meant as a real-time data integration tool. Therefore the connection between the two systems does not impose sharing of metadata other than the asset id of the media file and maybe the catalog id, while still allowing the freedom to map more metadata fields if desired.

Setup

In the adlibweb.xml file of the WebAPI server that you wish to use to communicate with the Portfolio server, the <imageServerConfiguration> section must be adapted to include references to Portfolio, for example:

<imageServerConfiguration name="images">
  <servertype>FileSystem</servertype>
  <path></path>
  <cachePath>C:\Data\Axiell\ModelAppl4.2SQL\imageCache</cachePath>
  <ImagePlugin type="Adlib.Portfolio.Imaging.Plugin.PortfolioImagePlugin, PortfolioImagePlugin">
    <BaseUrl>http://server:8090/ws/1.0/AssetService?wsdl</BaseUrl>
    <UploadUrl>http://server:8090/FileTransfer/upload</UploadUrl>
    <AutosyncFolder>::Portfolio:axiell-files:</AutosyncFolder>
    <UserName>axiellsystem</UserName>
    <Password>ourdifficultpassword</Password>
    <Catalog>FE840E4-A642-324E-6B97-7B1C2FEEF97</Catalog>
    <Mappings>
      <Mapping Source="CatalogID">portfolio.catalogID</Mapping>
      <Mapping Source="RID">reference_number</Mapping>
    </Mappings>
  </ImagePlugin>
  <deleteAllowed>true</deleteAllowed>
</imageServerConfiguration>

For each catalog you wish to address, a separate <imageServerConfiguration> is required, so even if you address a single catalog, consider making a new, separate <imageServerConfiguration> for Portfolio, instead of adapting the <imageServerConfiguration> section already present in your adlibweb.xml file.

The plugin-specific settings are all contained in the <imagePlugin> sub section (except for the deleteAllowed property) and have the following meaning:

`Property`	Description
`BaseUrl`	must contain the URL to the Portfolio web service used to download images from Portfolio Server. Replace `server:8090` by the relevant server name and port number, the rest of the path must always be: `/ws/1.0/AssetService?wsdl`
`UploadUrl`	must contain the URL to the Portfolio file transfer server used to upload images to Portfolio. Replace `server:8090` by the relevant server name and port number, the rest of the path must always be: `/FileTransfer/upload`
`AutosyncFolder`	the auto sync folder as set in Portfolio and thus used by the file transfer server to put the uploaded images in. (The colons in the path represent backslashes.)
`UserName`	the user name to be used to log in to Portfolio.
`Password`	the password to be used to log in to Portfolio.
`Catalog`	a single catalog id used to store and retrieve images in and from Portfolio. This implies that an extra `<imageServerConfiguration>` section (with its own unique name) needs to be defined per catalog id. The Axiell WebAPI should have ‘publisher’ access to this catalog.
`Mappings`	A list of field mappings from Portfolio metadata to Collections fields. The `<Mappings>` node can contain one or more `<Mapping>` nodes, each `<Mapping>` node has a `Source` attribute containing the name of a metadata field in Portfolio, while the content of the node itself is the name of a Collections field into which the retrieved metadata must be stored. When a media file is ingested into the DAMS, Portfolio creates an asset/item id for it and may extract other metadata from the file itself to store together with the file reference in the DAMS record. Any mapped metadata is returned as AdlibXML after ingesting or retrieving a media file from within Axiell Collections. Note that the mapping from RID to reference_number is required to be able to get the unique asset identifier from Portfolio into the Collections record! The CatalogId is not mandatory, but when stored in the Collections reproduction record as well, it enables the Axiell WebAPI to make a direct call to the Portfolio API for this asset. Note that although it’s possible to map any field you like, these fields will only be copied to the Collections record when the media file is being linked, afterwards there will never be any new synchronization should the DAMS record be updated. So, from that perspective it’s probably best to keep the mapping as limited as possible.
`deleteAllowed`	allows the Axiell WebAPI user to (attempt to) delete content from Portfolio and the file system (simultaneously), when set to `true`. The default value for this optional property is `false`. This functionality has only been implemented in the Axiell Portfolio plugin, not in Axiell Collections, so to delete content from the DAMS you would need a direct call to the Axiell WebAPI similar to: `wwwopac.ashx?command=deletecontent&server=images&value=530`, in which `server` must reference the appropriate Collections image server name and `value` the asset id.